User Interface : Customizing the Soft Input Panel Keyboard to Accept Only Numbers

1. Problem

You need to provide a virtual keyboard (also called a Soft Input Panel, or SIP) that accepts only numbers so users can insert numeric values into a text field.

2. Solution

You can use the InputScope property provided by the TextBox control and use the KeyDown event to exclude keys that are not needed.

3. How It Works

When the user has to insert information in your application and taps on a text field, a SIP keyboard appears, allowing the input of text. By using the InputScope attribute in your XAML code, you can customize the SIP in order to help users during text input.

You can use one of the values available from the InputScopeNameValue enumerator, as shown in Table 3-1. For example, if you use the TelephoneNumber value, the tapped text box will show the panel used to compose a telephone number.

You can use a combination of the InputScope attribute and the KeyDown event handler to customize the SIP behavior.

This recipe creates a SIP layout that accepts only numeric digits. You will customized the text box with the TelephoneNumber SIP layout and disable the input of non-numeric keys.

4. The Code

To demonstrate this recipe, you have to open the 7Drum project from the companion code by using Visual Studio 2010 and then focus on the Exercises page. It contains some data describing the exercise, such as the exercise's name and duration. It is the Duration text box that has to be numeric and accept only numeric digits.

In the Exercise.xaml file, you define the text box fields that compose the input form to specify an exercise. Note that the Duration text box field has the InputScope set to the TelephoneNumber value:

. . .
        <!--ContentPanel - place additional content here-->
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <StackPanel>
                <Grid>
                    <Grid.RowDefinitions>
                        <RowDefinition Height="Auto"/>
                        <RowDefinition Height="Auto"/>
                        <RowDefinition Height="*"/>
                    </Grid.RowDefinitions>
                    <Grid.ColumnDefinitions>
                        <ColumnDefinition Width="Auto" />
                        <ColumnDefinition Width="*" />
                    </Grid.ColumnDefinitions>

<TextBlock Grid.Row="0" Grid.Column="0"
                     Text="Name:" Style="{StaticResource PhoneTextNormalStyle}"
                     VerticalAlignment="Center" />
                    <TextBox Grid.Row="0" Grid.Column="1" x:Name="txtName" />
                    <TextBlock Grid.Row="1" Grid.Column="0" Text="Description:"
                    Style="{StaticResource PhoneTextNormalStyle}"
                    VerticalAlignment="Center" />
                    <TextBox Grid.Row="1" Grid.Column="1" x:Name="txtDescription"
                    AcceptsReturn="True" Height="300"/>
                    <TextBlock Grid.Row="2" Grid.Column="0" Text="Duration (min):"
                    Style="{StaticResource PhoneTextNormalStyle}"
                    VerticalAlignment="Center" />
                    <TextBox Grid.Row="2" Grid.Column="1" x:Name="txtDuration"
                    InputScope="TelephoneNumber" KeyDown="txtDuration_KeyDown"/>
                </Grid>
            </StackPanel>
        </Grid>
. . .

					  

In the Exercise.xaml.cs code, the KeyDown event handler ensures that no numeric digits are inserted in the Duration text box. The KeyEventArgs parameter provided by the KeyDown event handler contains the Key property that represents the pressed key. You can use this property to check that the pressed key is not the space key or other non-numeric key such as # or *. In this case, you can set the Handled property to true so that the key is accepted by the Duration text box. Otherwise, you have to set the Handled property value to false so that the key is not accepted.

private void txtDuration_KeyDown(object sender, KeyEventArgs e)
        {
            if (e.Key != Key.Space && e.Key != Key.D8 && e.Key != Key.D3 &&
                e.Key != Key.Unknown)
                e.Handled = false;
            else
                e.Handled = true;
        }

5. Usage

Press Ctrl+F5 from Visual Studio 2010 so that the application is deployed to either the Windows Phone 7 Emulator or the Windows Phone 7 device. The application starts. Select the Training menu item from the main page and then select the Add application bar button to add a new exercise.

The Exercise page loads, and you will see the text boxes shown in Figure 1.

Figure 1. The Exercise page with the Duration numeric field

Now tap the Duration text box, and the TelephoneNumber layout of the Soft Input Panel virtual keyboard appears (see Figure 2).

Figure 2. The customized TelephoneNumber virtual keyboard

Try to press numeric and non-numeric keys, and you will see that only the former are allowed.